The Points object contains the following methods:
The AddPoint method adds the point specified by the tag to the cache.
AddPoint(Tag As String, [NotifyHyperPoint As Variant])
| Parameter | Required | Description |
|---|---|---|
|
Tag |
Yes |
A tag string that indicates which point to monitor. (See CygNet Tag String Formats.) Note that the tag string can take any of the optional parameters listed below. |
|
NotifyHyperPoint |
No |
Identifies the name of the HyperPoint to notify when the tag information in the Points object changes. |
If the optional NotifyHyperPoint parameter is used and the tag’s real-time record or configuration record is changed, the specified HyperPoint’s OnPointChange event is triggered. The NotifyHyperPoint parameter is typically This, which refers to the current HyperPoint (see the example). The AddPoint method is not typically used in CygNet Studio because points can be referenced without first adding them to a Points object.
Example
The following example uses the STATUSPT HyperPoint’s OnInitializeEx event to assign two points to the Points object. The method passes the current HyperPoint’s name, "STATUSPT," as the HyperPoint to notify when one of these points’ records changes.
|
Sub STATUSPT_OnInitializeEx(This) ''Add LTANK, SPUMP tags to the Points Object to notify STATUSPT of real-time record updates Points.AddPoint "CYGDEMO.UIS::JONES45.LTANK", This Points.AddPoint "CYGDEMO.UIS::JONES45.SPUMP", This End Sub |
The required Tag string can include any of the following optional parameters to indicate that the HyperPoint’s OnPointChange event will run only when the specific property changes, rather than running when any one of them changes:
| Optional String | Required | Description |
|---|---|---|
|
;VALUE |
No |
Includes the base status, extended status, value, or alternate value. The value is always included by default. |
|
;TIMESTAMP |
No |
Includes the value and the timestamp. |
|
;ACK |
No |
Includes the value and the alarm record change. |
|
;TIMEONLY |
No |
Includes only the timestamp. |
|
;ACKONLY |
No |
Includes only the alarm record change. |
Example
The following example will include the value and the timestamp:
|
Points.AddPoint "CYGDEMO.UIS:TANK_LEVEL;TIMESTAMP", TANK_LEVEL_CMD |
The AddPointsArray method adds the points in a given array of tags to the cache.
AddPointsArray(ArrTags As Variant, EnableAlarmAck As Boolean, [NotifyHyperPoint As Variant])
| Parameter | Required | Description |
|---|---|---|
|
ArrTags |
Yes |
An array of tags to add. (See CygNet Tag String Formats.) |
|
EnableAlarmAck |
Yes |
A Boolean value indicating whether or not to enable alarm acknowledgment. |
|
NotifyHyperPoint |
No |
Identifies the name of the HyperPoint to notify when the tag information in the Points object changes. |
If the optional NotifyHyperPoint parameter is used and the tag’s real-time record or configuration record is changed, the specified HyperPoint’s OnPointChange event is triggered. The NotifyHyperPoint parameter is typically This, which refers to the current HyperPoint (see the example). The AddPointsArray method is not typically used in CygNet Studio because points can be referenced without it. However, it can be useful in situations where the names of the points to be added are stored in an array, or need to be accessed sequentially at a later time.
Example
The following HyperPoint OnInitializeEx event contains an example of adding an array of points to the Points object.
|
Sub STATUS_OnInitializeEx(This) Dim arrPoints Redim arrPoints(2)
'Fill array with some point tags arrPoints(0) = "CYGDEMO.UIS:METER206_PSTATIC" arrPoints(1) = "CYGDEMO.UIS:METER206_SPUMP" arrPoints(2) = "CYGDEMO.UIS:METER206_VOLTIB"
'Add the array to the points object Points.AddPointsArray arrPoints, False End Sub |
The EnableUpdate method enables or disables updating of the Points object.
EnableUpdate(Enable As Boolean)
| Parameter | Required | Description |
|---|---|---|
|
Enable |
Yes |
A Boolean value that enables updates if True and disables updates if False. |
If updating is disabled, auto refresh of the Points object is prevented. That is, if a point in the Points object has a value or status change, the OnPointChange event in the HyperPoint will not be triggered even if it is set to receive point updates by the AddPoint method. In the HSS, updates are enabled by default. Changing the EnableUpdate property in one HyperPoint script will change it for all scripts (it is a global property). The use of this function is rare and not generally needed except in more complex situations.
Example
The following example enables updating.
|
Sub enableUpdate() Points.EnableUpdate True edtMessageBox.Text = "Updating enabled" End Sub |
The GetPointStatusAttribute method returns the requested attribute of the point status.
GetPointStatusAttribute(BaseStatus As Integer, UserStatus As Long, Attr As String) As Variant
| Parameter | Required | Description |
|---|---|---|
|
BaseStatus |
Yes |
The base status bits. |
|
UserStatus |
Yes |
The user status bits. |
|
Attr |
Yes |
The point attribute to retrieve. The value of this parameter can be one of the following:
|
Example
The following example displays the data type "AO" in a message box. See the Point object for more information.
|
Sub getTagList()
Option Explicit
'Create a Points object Dim Points : Set Points = CreateObject("CxScript.Points")
'Define base status and user status values 'These values will typically come from a point’s Status and UserStatus properties. 'Refer to the Point Object in CxScript for more information.
Dim base_status : base_status="199" Dim user_status : user_status="12648448"
'Specify the attribute to retrieve Dim pointAttribute : pointAttribute = "pointstatedescription"
'Issue method to retrieve attribute Dim pointAttributeValue : pointAttributeValue = Points.GetPointStatusAttribute(base_status, user_status, pointAttribute)
MsgBox pointAttribute & " = " & pointAttributeValue
End Sub |
The GetPointsXML method returns point data in XML DOM format.
GetPointsXML(RequestXML As String) As String
| Parameter | Required | Description |
|---|---|---|
|
RequestXML |
Yes |
The request string indicating which fields to be retrieved and for which points. |
This method takes an XML string specifying the points and parameters to return and inserts the data in the return XML string. The request string is in the following format:
|
<cygPtInfo> <Parameters> <Value format=format /> <TimeStamp formatUTC=formatUTC /> <Status format=format /> <StatusTxt /> <Units /> <AlarmAck /> <Desc /> </Parameters> <Points> <node1 cygTag=tag /> <node2 ... </Points> </cygPtInfo> |
Parameters need to be included only for desired fields (names are case sensitive). Any number of points can be specified in the "Points" tag. The parameters listed in the following table comprise some the available options:
| Parameter | Returns | Attributes | |
|---|---|---|---|
|
AlarmAck |
The alarm acknowledgment status (0=unacknowledged; 1=acknowledged; 2=no alarm). |
N/A |
|
|
Desc |
The description of the point. |
N/A |
|
|
Status |
The status bit of the point. |
The Status parameter accepts an optional format attribute. When this attribute is set to "web", the status bit is converted to a string. The returned XML is identical to the request XML except that the indicated parameters are included as attributes in each "node" tag. Example
|
|
|
StatusTxt |
The description of the point status. |
N/A |
|
|
TimeStamp |
The timestamp associated with the current value of the point. |
The formatUTC attribute of the TimeStamp parameter can be either true (for UTC timestamp) or false (for local timestamp). When not specified, the timestamp is local. Example
|
|
|
Units |
The primary units of the point. |
N/A |
|
|
Value |
The current value of the point. |
The Value parameter can take an optional format string that indicates the string format of the point value. For example, format="##,##0.00" returns a string version of a number with a comma and two decimal places. See the MSDN Library for a specification of VBScript format strings. Example
|
Example
The following method saves XML data for the value, timestamp, and status of an inputted array of point tags.
|
Function GetXMLData(arrPoints) Dim strXMLReq, i
'Add points to the Points object and get current data Points.AddPointsArray arrPoints, True Points.ResolveNow(2)
'Create XML request string strXMLReq = "<cygPtInfo>" &"<Parameters>" &"<Value/>" &"<TimeStamp/>" &"<Status/>" &"</Parameters>" &"<Points>"
For i=lbound(arrPoints) To ubound(arrPoints) strXMLReq = strXMLReq & "<node" & CStr(i+1) & " cygTag="& chr(34) & arrPoints(i) & chr(34) & "/>" Next
strXMLReq = strXMLReq &"</Points>"&"</cygPtInfo>"
'Get response XML GetXMLData = Points.GetPointsXML(strXMLReq) End Function |
See the CxScript Enumeration Attributes table in the Enumeration Constants section.
The GetPointTagList method returns a list of point tags for the specified criteria.
GetPointTagList(PointCfgOrCvsSiteService As String, Filter As String, GetLongID As Boolean, TagList As Variant)
| Parameter | Required | Description |
|---|---|---|
|
PointCfgOrCvsSiteService |
Yes |
Defines the CVS site and service in "site.service" format. |
|
Filter |
Yes |
A semicolon delimited naming filter to select certain tags. Possible filters include:
Wildcards are not allowed. Any of the other properties defined in PNT header record are also legal. |
|
GetLongId |
Yes |
Set to True to receive Long IDs, or False to receive Short IDs. |
|
TagList |
Yes |
Output. Stores the list of retrieved tags. |
Example
The following example gets the short ID for all points in CYGDEMO.UIS and stores them in a list box.
|
Sub getTagList() Dim arrTags, tag
Points.GetPointTagList "CYGDEMO.UIS", "FACILITYID=" & facility, True, arrTags lstTags.ResetContent For Each tag In arrTags lstTags.AddString(tag) Next edtMessage.Text = "Done" End Sub |
To use any of the PNT header record properties in GetPointTagList, your filter must include at least one of these indexed attributes:
If you include one of those, you can also include other non-indexed fields from the PNT header record. You must include one of the parameter(s) on the left column in the filter. Some of them will allow additional filtering parameters.
| Required Parameters | Additional Parameters Allowed |
|---|---|
| indexed1 | Yes |
| indexed2 | Yes |
| indexed3 | Yes |
| systemname & udc | No |
| systemname & udc & facility | Yes |
| systemname & facility | Yes |
| systemname | No |
| facility & udc | Yes |
| udc | No |
| facility | Yes |
| site & service | No |
| All tags | No |
This means that when you are using facility as your filter, you can add additional filters like AnyCfgBitEnabled, Activestatus, etc. to get the desired point list.
Examples
The filtering below gives an array of points which have active_flag and AnyCfgBitEnabled set to 1. It works with 1 and 0.
|
Points.GetPointTagList "CYGNET.UIS","FACILITY=WELL00_RD;AnyCfgBitEnabled=1;activestatus=1",True, arrTagList |
If you would like to include only a particular UDC points, then you can add UDC to the filter as shown below.
|
Points.GetPointTagList "CYGNET.UIS","FACILITY=WELL00_RD;UDC=TDDOWNT;AnyCfgBitEnabled=1;activestatus=1",True, arrTagList |
The arrTagList would contain the list of point for the Facility indicated in the filter for which Any Config Bit is enabled and Active flag is Y.
Important Note: Point databases are potentially too large to allow for filters using any of the PNT header properties. Instead you filter based on a limited number of pre-defined indexed fields, and then filter further based on the results of the indexed read. The generic database fields like length, version, record_type, and active_flag are not supported by this function call.
The GetPointTagListForFacilities method takes in an array of facility tags and returns an array of objects that have tag information elements.
GetPointTagListForFacilities(pvArrFacilityTags As Variant, TagList As Variant)
| Parameter | Required | Description |
|---|---|---|
|
ArrFacilityTags |
Yes |
An array of facility tags. |
|
TagList |
Yes |
Output. Stores the list of retrieved tag objects. |
Example
The following example gets the tag information for the points for the facilities CYGDEMO.UIS::WELL and CYGDEMO.UIS::TANK.
|
Dim arrFacs, arrTagObjs, objTag, strTags arrFacs = Array("CYGDEMO.UIS::WELL", "CYGDEMO.UIS::TANK")
Points.GetPointTagListForFacilities arrFacs, arrTagObjs
For Each objTag in arrTagObjs strTags = strTags & objTag.Tag & vbcr Next
MsgBox strTags |
The GetUdcList method returns the UDC list for the specified facility tag.
GetUdcList(FacilityTag As String, UdcList As Variant)
| Parameter | Required | Description |
|---|---|---|
|
FacilityTag |
Yes |
The request string indicating which fields to be retrieved and for which points. |
|
UdcList |
Yes |
The UDC list returned by this method. |
Example
The following example lists all UDCs for the facility "CYGDEMO.UIS::ENTOPS".
|
Sub Dim aryUdcs Points.GetUdcList "CYGDEMO.UIS::ENTOPS", aryUdcs
Dim i, strMsg For i = 0 To UBound(aryUdcs) strMsg = strMsg + aryUdcs(i) + vbCr Next
MsgBox strMsg End Sub |
The Point method returns a Point object representing the point associated with the specified tag.
Point(Tag as String) As Point
| Parameter | Required | Description |
|---|---|---|
|
Tag |
Yes |
A tag string from which to build the Point object. (See CygNet Tag String Formats.) |
The returned reference is a Point object, which is a static snapshot of the point at the current moment. Properties of this Point object are read only. If the Tag parameter is an invalid tag string, an empty Point object will be returned. For more information about the Point object, see Points Object.
Examples
The following function returns the value for a given tag string by declaring a Point object from the Points object.
|
Function GetPointValue (tagString) Dim objPoint
'Create a Point object and return its value Set objPoint = Points.Point(tagString) GetPointValue = objPoint.Value End Function |
The next example gives a HyperPoint used for data thinning. It uses the AddPoint method and sets a timer so that OnTimer is called once an hour. The hourly value of the MYPOINT point is then stored in a separate UIS point, METER206_MYPOINT_THIN, effectively trimming the data to a manageable amount for trending and analysis.
|
Sub MYPOINT_THIN_OnInitializeEx(This) 'Add a point to be monitored Points.AddPoint "CYGDEMO.UIS:METER206_MYPOINT"
'Set a timer to update every hour Timer.Set This, 3600000 End Sub
Sub MYPOINT_THIN_OnTimer(This) 'Obtain the Point object Set pStaticPoint = Points.Point("CYGDEMO.UIS:METER206_MYPOINT")
'Assign the current MYPOINT value to a separate point SetPoint, pStaticPoint.Value End Sub |
The ResolveNow method updates all points in the points object that have not been resolved with data from the CVS, Point Service, or both.
ResolveNow(resolveFlag As ResolveNowType)
| Parameter | Required | Description |
|---|---|---|
|
resolveFlag |
Yes |
This parameter takes one of the values in the ResolveNowType enumeration table and indicates from which services to resolve points: CVS only (0), Point Service only (1), or both service types (2). |
Whereas the UpdateNow method updates all points in a Points object, ResolveNow updates just the subset that have not been resolved. This can be used in cases where you suspect that the script engine has not resolved a set a points before you need to retrieve their data.
In non-HSS environments, EnableUpdate is turned off by default for declared Points objects, so updating can be achieved using the UpdateNow or ResolveNow methods rather than enabling updates.
Example
The following example updates unresolved points for both service types.
|
Sub enableUpdate() Points.ResolveNow 2 edtMessageBox.Text = "Points resolved" End Sub |
The UpdateNow method forces an immediate update of items in the Points object with data from the CVS, Point Service, or both.
UpdateNow(UpdateFlag As UpdateNowType)
| Parameter | Required | Description |
|---|---|---|
|
UpdateFlag |
Yes |
This parameter takes one of the values in the UpdateNowType enumeration table. This table contains constants that specify the service(s) from which to update the Points object: CVS only (0), Point Service only (1), or both service types (2). |
This method can be used in cases where you suspect that the script engine has not resolved the majority of points before you need to retrieve their data.
In non-HSS environments, EnableUpdate is turned off by default for declared Points objects, so updating can be achieved using the UpdateNow or ResolveNow methods rather than enabling updates.
Example
The following example updates all points for both service types.
|
Sub enableUpdate() Points.UpdateNow 2 edtMessageBox.Text = "Points updated" End Sub |
|
|
|
